home *** CD-ROM | disk | FTP | other *** search
/ Aminet 22 / Aminet 22 (1997)(GTI - Schatztruhe)[!][Dec 1997].iso / Aminet / dev / c / focs.lha / focs.doc < prev    next >
Text File  |  1997-10-26  |  4KB  |  108 lines
  1. Introduction:
  2.  
  3. This is a little tool I made for all programmers who need to call SetFunction()
  4. from C (or C++). It is intended to make life easier and to make source files more
  5. readable.
  6.  
  7. Usually, when one want to use SetFunction(), he/she must look in .fd files or
  8. #pragma statements to find the LVO of each function he/she want to patch (*). This
  9. leads to source files difficult to understand and maintain, since each call to
  10. SetFunction() looks like:
  11.  
  12. oldfunction=SetFunction(Execbase,-690,myfunction);
  13.  
  14. where you can't understand very well which function is being patched, unless you
  15. add tons of comment lines to each call.
  16.  
  17. (*)= All the system libraries offsets exist through amiga.lib, but 3rd party
  18. libraries don't. This is why I made FOCS!
  19.  
  20. FOCS (that stands for Function Offset Creator for SetFunction() ), takes a file
  21. with LVOs and creates nice C header (.h) files, with a symbol definition for each
  22. function found in the LVO file.
  23. So the example above will look like:
  24.  
  25. oldfunction=SetFunction( Execbase, FOS_FreeVec, myfunction );
  26.  
  27. Nice, isn't it ?
  28.  
  29. FOCS version 1.0 support the following file formats:
  30.  - SAS C #pragma files
  31.  - StormC #pragma files (similar but not the same stuff).
  32.  - FD files (those who started it all).
  33.  - GCC inline's (hopefully... only the new, preprocessor based format is
  34.    supported). 
  35.  
  36. In future versions these format may also be supported:
  37.  - Assembler .LVO files.
  38.  - Aztec C #pragma files.
  39. (Does anybody care about these ?)
  40.  
  41.  
  42. Installation:
  43.  
  44. Smash the corresponding executable anywhere in you search path. The file named
  45. FOCS is for 68020+ systems. If you really need a plain 68000 version, use the
  46. patch file focs.pch with spatch (not included) (if you're a programmer,
  47. you'll know what to do).
  48.  
  49. Usage:
  50.  
  51. Pretty simple, I think. Just smash any input file on the command line; wildcards
  52. are welcome. Wildcards in the path part of the file are NOT welcome.
  53. Example:
  54. focs #?_pragmas.h graphics_lib.fd
  55.  
  56. For each function offset a corresponding #define will be built, with 'FOS_'
  57. before the function name. Example (from fos_exec.h): 
  58.  
  59. #define FOS_FreeVec -690
  60. #define FOS_AllocVec ....
  61.  
  62. You'll just have to #include the necessary FOCS files in your code, and you'll
  63. have everything correctly defined. 
  64. For .fd files, you can add 'PRIVATE' to the command line to make FOCS generate
  65. #define symbols for private functions too, so you can do some nice low-level
  66. hacking!
  67.  
  68. All the corresponding output files will be generated in the corresponding
  69. directory.
  70. Generally the output file name is formed using the library name, with 'fos_'
  71. (Function Offsets for SetFunction() ) before and '.h' after: so the FOCS file for
  72. exec.library is "fos_exec.h", and so on.
  73.  
  74. HINT: if you don't want to mess up with header files too much, you can create a
  75. 'fos' directory in your include: path, and store every FOCS file there.
  76.  
  77. Bugs (and other little nasty crawling things):
  78.  
  79.  - Filetype recognition isn't perfect, so if you submit a file which is slightly
  80.    modified, FOCS will barf. Syntax recognition is quite strict; this is most
  81.    important for StormC files, where a line like:
  82.  
  83.    #pragma amicall(UtilityBase, 0x3c, MapTags(a0,a1,d0))
  84.  
  85.    is considered valid, but
  86.  
  87.    #pragma amicall( UtilityBase, 0x3c, MapTags(a0,a1,d0) )
  88.  
  89.    will break everything; so keep in mind FOCS works well with standard, common
  90.    and correct header files, but will fail on statments badly written or just
  91.    a bit 'out of standard'. A good example is xfd_master_pragmas.h : the first
  92.    part of the file is a Aztec C pragma file, which is mistaken as StormC. In
  93.    this case, FOCS fails completely. Eliminating the first part will cure the
  94.    problem.
  95.  
  96.  - Stack usage is big, compared to FOCS size (almost everything is allocated on
  97.    the stack). Ensure you've a stack of 32k bytes or more.
  98.  
  99.  
  100. Author:
  101.  
  102. It's me! Send bug reports and other things (preferably nice ones) to:
  103. Andrea Vallinotto AKA andrea.vallinotto@torino.alpcom.it , or
  104. 2:334/21.13 (FidoNet) and 39:101/402.13 (AmigaNet).
  105.  
  106. Happy patching !
  107.  
  108.